Globalization Library

Namespace: $GG.globalization

Overview

The $GG Globalization object interface provides a comprehensive set of methods and classes designed to manage and facilitate language translation within your application. The core of this functionality is encapsulated in the ggLanguage class, which extends the $GG.types.service class to leverage common API request handling and header generation.

Including In Html

<head>
    ...
    <script src="https://launch.gig.game/api/js?key={API KEY HERE}&libraries=globalization"></script>
    ...
</head>

Implementing in Application

When integrating the globalization features into your application, it's crucial to understand how to manually invoke language translation and utilize the auto-translate capabilities and <translate> elements effectively. This section will guide you through both approaches.

Implementing in Javascript

To manually call the translation functionality from JavaScript, you need to interact with the ggLanguage class provided by the framework. Here�s a step-by-step guide:

Accessing the ggLanguage Instance: To access the ggLanguage instance and its methods, use the global $GG.globalization.language object.
```
const { setSourceLanguage, translate, translateDom } = $GG.globalization.language;
```
Setting the Source Language: To change the source language, call the setSourceLanguage method. This method updates the source language code and resets the translation cache.
```
$GG.globalization.language.setSourceLanguage('es') // Set source language to Spanish
  .then(() => {
    console.log('Source language set and cache reset.');
  });
```
Translating Text: To translate specific text, use the translate method. It accepts a string to translate and an optional force parameter to bypass cache and always fetch a fresh translation.
```
$GG.globalization.language.translate('Hello, world!')
  .then(translatedText => {
    console.log(translatedText); // Output: Translated text in the target language
  });
```
Translating the Entire DOM: To translate all text elements in the DOM that use auto-translate attributes or <translate> tags, call the translateDom method.
```
$GG.globalization.language.translateDom()
  .then(() => {
    console.log('DOM translation complete.');
  });
```

Implementing in HTML

Globalization can be further enhanced by utilizing specific HTML attributes and elements. Here's how you can integrate them into your application:

Using the autotranslate Attribute: The autotranslate attribute is used to mark HTML elements whose content should be automatically translated. When this attribute is present, the content of the element is processed and translated when you call the translateDom method.
```
<div autotranslate>
  Welcome to our website!
</div>
```
In this example, the text within the <div> will be translated according to the current language settings when translateDom is executed.
Using the <translate> Element: The <translate> element is a custom HTML tag used for marking text that should be replaced with its translation. This element should be used when you want to replace a block of text with its translated version.
```
<translate>Welcome to our website!</translate>
```
The content inside the <translate> tag will be replaced with the translated text when translateDom is called. Note that the <translate> tag should be properly processed and removed or replaced with the translated text.

Testing Globalization Features

When developing and testing the globalization features, you can control the language setting by modifying the gg-language attribute in the <body> tag. This attribute allows you to simulate different languages in your application without making changes to the actual codebase.

Example of setting the language attribute in the <body> tag:

<body gg-gamekey="{development game key}"
      gg-playerkey="00000000-0000-0000-0000-000000000001"
      gg-language="en">
  <!-- Your application content goes here -->
</body>

In this example, the gg-language attribute is set to "en", indicating that the content should be displayed in English. You can change this value to other language codes (e.g., "es" for Spanish) to test translations in different languages.

By understanding and utilizing these methods and attributes, you can effectively manage and test the globalization features in your application, ensuring that your content is appropriately translated for users around the world.